package vip.liux.contracts.security.core.extensions;


import java.time.OffsetDateTime;
import java.util.Optional;

/**
 * 提供用于实现账户锁定（包括访问失败次数和锁定状态）信息存储的抽象接口。
 *
 * @param <TUser> 表示用户的类型。
 */
public interface IUserLockoutStore<TUser> extends IUserStore<TUser> {
    /**
     * 获取用户上次锁定到期的时间（如果有）。
     * 过去的时间表示用户未被锁定。
     *
     * @param user 要查询锁定日期的用户。
     * @return 用户上次锁定到期的时间，若无则为 Optional.empty()。
     */
    Optional<OffsetDateTime> getLockoutEndDate(TUser user);

    /**
     * 将用户锁定到指定的结束时间。设置为过去的时间可立即解锁用户。
     *
     * @param user       要设置锁定日期的用户。
     * @param lockoutEnd 锁定结束时间。
     */
    void setLockoutEndDate(TUser user, Optional<OffsetDateTime> lockoutEnd);

    /**
     * 记录一次访问失败，增加失败次数。
     *
     * @param user 要增加失败次数的用户。
     * @return 增加后的失败次数。
     */
    int incrementAccessFailedCount(TUser user);

    /**
     * 重置用户的访问失败次数。
     *
     * @param user 要重置失败次数的用户。
     */
    void resetAccessFailedCount(TUser user);

    /**
     * 获取指定用户当前的访问失败次数。
     *
     * @param user 要查询的用户。
     * @return 失败次数。
     */
    int getAccessFailedCount(TUser user);

    /**
     * 获取指定用户是否可以被锁定的标志。
     *
     * @param user 要查询的用户。
     * @return 如果可以被锁定返回 true，否则返回 false。
     */
    boolean getLockoutEnabled(TUser user);

    /**
     * 设置指定用户是否可以被锁定。
     *
     * @param user    要设置的用户。
     * @param enabled 是否允许锁定。
     */
    void setLockoutEnabled(TUser user, boolean enabled);
}